.TH std::basic_stringbuf::basic_stringbuf 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_stringbuf::basic_stringbuf \- std::basic_stringbuf::basic_stringbuf

.SH Synopsis
   explicit basic_stringbuf( std::ios_base::openmode which =
                                 std::ios_base::in |                      \fI(until C++11)\fP
   std::ios_base::out );
   explicit basic_stringbuf( std::ios_base::openmode which );             \fI(since C++11)\fP
   basic_stringbuf()
       : basic_stringbuf( std::ios_base::in | std::ios_base::out     \fB(2)\fP  \fI(since C++11)\fP
   ) {}
   explicit

       basic_stringbuf( const std::basic_string<CharT, Traits,
   Allocator>& s,                                                    \fB(3)\fP
                        std::ios_base::openmode which =

                            std::ios_base::in |
   std::ios_base::out );
   explicit basic_stringbuf( std::basic_string<CharT, Traits,
   Allocator>&& s,

                             std::ios_base::openmode which =         \fB(4)\fP  \fI(since C++20)\fP

                                 std::ios_base::in |
   std::ios_base::out );
   basic_stringbuf( std::ios_base::openmode which, const             \fB(5)\fP  \fI(since C++20)\fP
   Allocator& a );
   explicit basic_stringbuf( const Allocator& a )
       : basic_stringbuf( std::ios_base::in |                        \fB(6)\fP  \fI(since C++20)\fP
   std::ios_base::out, a ) {}
   template< class SAlloc >

   explicit basic_stringbuf( const std::basic_string<CharT,
   Traits, SAlloc>& s,                                               \fB(7)\fP  \fI(since C++20)\fP
                             std::ios_base::openmode which =

                                 std::ios_base::in |
   std::ios_base::out );                                         \fB(1)\fP
   template< class SAlloc >

   basic_stringbuf( const std::basic_string<CharT, Traits,
   SAlloc>& s,                                                       \fB(8)\fP  \fI(since C++20)\fP

                    std::ios_base::openmode which, const
   Allocator& a );
   template< class SAlloc >

   basic_stringbuf( const std::basic_string<CharT, Traits,
   SAlloc>& s,                                                       \fB(9)\fP  \fI(since C++20)\fP
                    const Allocator& a )

       : basic_stringbuf( s, std::ios_base::in |
   std::ios_base::out, a ) {}
   template< class StringViewLike >

   explicit basic_stringbuf( const StringViewLike& t,
                             std::ios_base::openmode which =         \fB(10)\fP (since C++26)

                                 std::ios_base::in |
   std::ios_base::out );
   template< class StringViewLike >

   basic_stringbuf( const StringViewLike& t,                         \fB(11)\fP (since C++26)

                    std::ios_base::openmode which, const
   Allocator& a );
   template< class StringViewLike >
   basic_stringbuf( const StringViewLike& t, const Allocator& a      \fB(12)\fP (since C++26)
   );
   basic_stringbuf( basic_stringbuf&& rhs );                         \fB(13)\fP \fI(since C++11)\fP
   basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a );     \fB(14)\fP \fI(since C++20)\fP
   basic_stringbuf( const basic_stringbuf& rhs ) = delete;           \fB(15)\fP \fI(since C++11)\fP

   The std::basic_streambuf base and the exposition-only data members buf and mode are
   initialized as follows.

   After initializing these subobjects, overloads (3-12) initialize the input and
   output sequences as if by calling init_buf_ptrs().

    Overload    std::basic_streambuf              buf                     mode
                       base
   \fB(1)\fP                                                            which
                                       implementation-defined      std::ios_base::in |
   \fB(2)\fP                                 (see below)
                                                                  std::ios_base::out
   \fB(3)\fP                                 s
   \fB(4)\fP                                 std::move(s)               which
   \fB(5)\fP
                                       a                           std::ios_base::in |
   \fB(6)\fP
              default-initialized                                 std::ios_base::out
   \fB(7)\fP                                 s                          which
   \fB(8)\fP
                                       {s, a}                      std::ios_base::in |
   \fB(9)\fP
                                                                  std::ios_base::out
   \fB(10)\fP                                {sv, Allocator()}          which
   \fB(11)\fP
                                       {sv, a}                     std::ios_base::in |
   \fB(12)\fP
                                                                  std::ios_base::out
   \fB(13)\fP       rhs                      std::move(rhs).str()
   \fB(14)\fP       (copy constructed)        {std::move(rhs).str(),    rhs.mode
                                       a}

   1,2) Overload
   \fB(1)\fP
   \fI(until C++11)\fP
   \fB(2)\fP
   \fI(since C++11)\fP is the default constructor. It is implementation-defined whether the
   sequence pointers (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) are
   initialized to null pointers.
   5,6) When the construction is complete, str.empty() is true.
   7) This overload participates in overload resolution only if std::is_same_v<SAlloc,
   Allocator> is false.
   10-12) Implicitly converts t to a string view sv as if by
   std::basic_string_view<CharT, Traits> sv = t;, then it is used as above in the
   table.
   These overloads participate in overload resolution only if
   std::is_convertible_v<const StringViewLike&,
                         std::basic_string_view<CharT, Traits>> is true.
   13,14) Overload \fB(13)\fP is the move constructor. It is implementation-defined whether
   the six sequence pointers in *this obtain the values which rhs had.
   When the construction is complete, rhs is empty but usable, and
     * Let rhs_p refer to the state of rhs just prior to this construction, the
       following expressions will evaluate to true:

     * str() == rhs_p.str()
     * getloc() == rhs_p.getloc()
     * gptr() - eback() == rhs_p.gptr() - rhs_p.eback()
     * egptr() - eback() == rhs_p.egptr() - rhs_p.eback()
     * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()
     * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()
     * Let rhs_a refer to the state of rhs just after this construction, the following
       expressions will evaluate to true:

     * !eback() || eback() != rhs_a.eback()
     * !gptr() || gptr() != rhs_a.gptr()
     * !egptr() || egptr() != rhs_a.egptr()
     * !pbase() || pbase() != rhs_a.pbase()
     * !pptr() || pptr() != rhs_a.pptr()
     * !epptr() || epptr() != rhs_a.epptr()
   15) The copy constructor is deleted; std::basic_stringbuf is not CopyConstructible.

.SH Parameters

   s     - a std::basic_string used to initialize the buffer
   t     - an object (convertible to std::basic_string_view) used to initialize the
           buffer
   a     - another allocator used to construct the internal std::basic_string
   rhs   - another basic_stringbuf
           specifies stream open mode. It is bitmask type, the following constants are
           defined:

           Constant          Explanation
           app               seek to the end of stream before each write
   which - binary            open in binary mode
           in                open for reading
           out               open for writing
           trunc             discard the contents of the stream when opening
           ate               seek to the end of stream immediately after open
           noreplace (C++23) open in exclusive mode

.SH Notes

   Typically called by the constructor of std::basic_stringstream.

   The level of support for the open modes other than std::ios_base::in and
   std::ios_base::out varies among implementations. C++11 explicitly specifies the
   support for std::ios_base::ate in str() and in this constructor, but
   std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have different
   effects on different implementations.

           Feature-test macro          Value    Std                Feature
   __cpp_lib_sstream_from_string_view 202306L (C++26) Interfacing string streams with
                                                      std::string_view

.SH Example

   Demonstrates calling the constructor of std::basic_stringbuf directly:


// Run this code

 #include <iostream>
 #include <sstream>

 int main()
 {
     // default constructor (mode = in | out)
     std::stringbuf buf1;
     buf1.sputc('1');
     std::cout << &buf1 << '\\n';

     // string constructor in at-end mode \fI(C++11)\fP
     std::stringbuf buf2("test", std::ios_base::in
                               | std::ios_base::out
                               | std::ios_base::ate);
     buf2.sputc('1');
     std::cout << &buf2 << '\\n';

     // append mode test (results differ among compilers)
     std::stringbuf buf3("test", std::ios_base::in
                               | std::ios_base::out
                               | std::ios_base::app);
     buf3.sputc('1');
     buf3.pubseekpos(1);
     buf3.sputc('2');
     std::cout << &buf3 << '\\n';
 }

.SH Output:

 1
 test1
 est12 (Sun Studio) 2st1 (GCC)

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to            Behavior as published              Correct behavior
                      1. overload \fB(1)\fP allocated no array object   1. removed the
   LWG 432 C++98      2. overload \fB(3)\fP did not specify how the     limitation
                      input                                       2. specified
                          and output sequences are initialized
                      overload \fB(3)\fP set epptr() to point one past
   LWG 562 C++98      the last underlying                         epptr() can be set
                      character if bool(which &                   beyond that position
                      std::ios_base::out) == true
   P0935R0 C++11      the default constructor was explicit        made implicit

.SH See also

                 constructs the string stream
   constructor   \fI\fI(public member\fP function of\fP
                 std::basic_stringstream<CharT,Traits,Allocator>)
